Skip to main content

SAML SSO Setup for Shakudo Hyperplane Platform

This guide explains how to configure SAML Single Sign-On (SSO) for the Shakudo Hyperplane platform using Azure Active Directory (AAD) and Keycloak. It assumes that the Keycloak realm is named Hyperplane and the client ID is istio.

Prerequisites​

  • Admin access to Azure Active Directory
  • Admin access to Keycloak instance
  • Keycloak server reachable by AAD (public DNS or reverse proxy)

Step 1: Create Enterprise Application in Azure AD​

  1. Log in to Azure Portal.
  2. Navigate to Azure Active Directory > Enterprise Applications.
  3. Click + New Application > Create your own application.
  4. Name it something like Shakudo Hyperplane SSO, select Integrate any other application you don't find in the gallery (Non-gallery), and click Create.

Step 2: Configure SAML in Azure AD​

  1. In the created application, go to Single sign-on > SAML.

  2. Under Basic SAML Configuration, click Edit and fill in:

    • Identifier (Entity ID):
      https://<your-keycloak-domain>/auth/realms/Hyperplane
    • Reply URL (Assertion Consumer Service URL):
      https://<your-keycloak-domain>/auth/realms/Hyperplane/broker/azuread/endpoint
      > Some of the app require you to put https://<your-keycloak-domain> so the Application will redirect you into correct entry page of Shakudo platform

  3. Click Save.

Step 3: Download SAML Metadata​

  1. In the Azure AD SAML configuration page, download the Federation Metadata XML, or copy the URL.
  2. Save it locally for import into Keycloak.

Step 4: Configure Keycloak Identity Provider​

  1. Log in to Keycloak Admin Console (https://<your-keycloak-domain>/auth/admin).
  2. Select the realm Hyperplane.
  3. Navigate to Identity Providers > Add provider > SAML v2.0.
  4. Set:
    • Alias: azuread
    • Import from URL / XML: Upload the XML metadata from Azure, or paste the XML url from the Step 3.
    • First Login Flow: first broker login
    • Sync Mode: force
  5. Click Save.

Step 5: Configure Attribute Mappers in Keycloak​

  1. In the Identity Provider (azuread) configuration page, scroll to the Mappers tab.
  2. Click Create to add each of the following mappers:

Mapper: username​

  • Name: username
  • Mapper Type: Attribute Importer
  • Attribute Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  • User Attribute Name: username

Mapper: email​

  • Name: email
  • Mapper Type: Attribute Importer
  • Attribute Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  • User Attribute Name: email

Mapper: given name​

  • Name: givenName
  • Mapper Type: Attribute Importer
  • Attribute Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
  • User Attribute Name: firstName

Mapper: surname​

  • Name: surname
  • Mapper Type: Attribute Importer
  • Attribute Name: http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
  • User Attribute Name: lastName

Optional: groups (if configured in Azure AD)​

  • Name: groups
  • Mapper Type: Attribute Importer
  • Attribute Name: http://schemas.xmlsoap.org/claims/Group
  • User Attribute Name: groups

Click Save for each.

Step 6: Test the SSO​

  1. Go to your Shakudo platform.
  2. You should be redirected to Azure AD for login.
  3. After login, you’ll be redirected back to the platform and logged in.

Notes​

  • If group/role mapping is needed, ensure Azure AD is sending the correct claims, and use mappers in Keycloak.
  • Ensure the clock time between Keycloak and Azure AD is synchronized to avoid token issues.

Enjoy seamless identity federation with Azure AD and the Shakudo Hyperplane platform 🚀